home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-02 / exec31.zip / README.DOC < prev    next >
Text File  |  1991-08-20  |  22KB  |  482 lines

  1.  
  2.                   An EXEC function with memory swap
  3.                    Version 3.1, released 91-08-20
  4.       
  5.                       Public Domain Software by
  6.                             Thomas Wagner
  7.                        Ferrari electronic GmbH
  8.  
  9.  
  10. This archive contains the sources for an 'EXEC' function that allows
  11. calling external programs, while optionally swapping out the memory
  12. image to EMS, XMS, or file. When swapping out, only a few K of main
  13. memory remain resident. The code and data stub is about 1k, the actual
  14. memory usage depends on memory fragmentation, and especially on the
  15. size of the environment variables. The resident memory usage
  16. typically ranges from 2K to 7K.
  17.  
  18. The Routines are compatible with 
  19.    Turbo C (Versions 1.x, 2.x, and C++ 1.0)
  20.    Borland C++ (Version 2.0),
  21.    Microsoft C (Versions 5.1 and 6.0), 
  22.    Watcom C (Version 8.0), 
  23.    Turbo Pascal (Versions 4.x and 5.x, 6.x not tested).
  24.  
  25. EMS (LIM 3.0 or above) or XMS is used automatically if there is
  26. enough space left, otherwise a temporary file is created. If the
  27. "TEMP=" or "TMP=" environment variable is present, the temporary file
  28. is created in the directory specified by this variable, otherwise it
  29. is created in the current directory.
  30.  
  31. For detailed usage and parameter information, see the file "exec.h" (C) 
  32. or "exec.pas" (Pascal).
  33.  
  34. The general format is
  35.  
  36.    retcode = do_exec (filename to execute,
  37.                       program parameter and redirection string,
  38.                       spawn options,
  39.                       memory needed (0xffff to always swap, 0 to never swap),
  40.                       environment pointer/flag)
  41.  
  42. for example:
  43.  
  44.    rc = do_exec ("cl", "-c -Od exec.c >&errout", USE_ALL, 0xffff, NULL);
  45.  
  46. or, for Pascal:
  47.  
  48.    rc := do_exec ('tpc', '/$D+ exec >&errout', USE_ALL, $ffff, false);
  49.  
  50. Redirection for standard input, standard output, and standard error
  51. is optionally handled by parsing the command parameter string for the
  52. standard redirection combinations:
  53.  
  54.    stdin:   <file
  55.    stdout:  >file    or >>file   to append
  56.    stderr:  >&file   or >&>file  to append
  57.  
  58. Redirection is supported by default, to disable it you must change
  59. the define in both spawn.asm and exec.c/exec.pas.
  60.  
  61. If the command to be executed is a BAT file, the command processor
  62. will be invoked automatically. The command processor will also be
  63. invoked if the command is empty. The COMSPEC environment variable is
  64. used to locate the command processor, any parameters present on the
  65. COMSPEC line are inserted into the parameter string.
  66.  
  67. An example:
  68.  
  69.    Given   COMSPEC=C:\DOS\COMMAND.COM /E:960
  70.            PATH=C:\DOS;C:\CMD
  71.            File B.BAT resides in C:\CMD
  72.            do_exec is called with ('b', 'one two >out', ...)
  73.  
  74.    Then the command executed is
  75.            C:\DOS\COMMAND.COM
  76.    with the parameter string
  77.            /E:720 /C C:\CMD\B.BAT one two
  78.    and standard output redirected to file 'out'.
  79.  
  80.  
  81.  
  82.                         CONTENTS
  83.                         ========
  84.  
  85. This archive contains the following files:
  86.  
  87.     README.DOC      This file
  88.     LIESMICH.DOC    German version of this file
  89.  
  90.     GETLANG.EXE     A helper program to extract a single-language
  91.                     version from the dual-language source. All C and
  92.                     Assembler sources (Pascal sources only partially)
  93.                     are commented in both English and German,
  94.                     which makes the code hard to read. For easier
  95.                     reading, you can use GETLANG to eliminate one
  96.                     of the languages.
  97.  
  98.          Usage:   GETLANG language compiler <infile >outfile
  99.             Where    language is 'E' for English or 'D' for German
  100.                      compiler is 'C' for C files, 'A' for Assembler,
  101.                      or 'P' for Pascal.
  102.  
  103.          Samples: GETLANG e a <spawn.asm >spawne.asm
  104.                   GETLANG e c <extest.c >exteste.c
  105.  
  106.     DEUTSCH.BAT     Batch-File to execute GETLANG for all source
  107.                     files, German version
  108.     ENGLISH.BAT     Batch-File to execute GETLANG for all source
  109.                     files, English version
  110.  
  111.     SPAWN.ASM       The main swap/exec function
  112.  
  113.         This file is common to the C and Pascal versions.
  114.         It must be assembled with Turbo-Assembler for use with
  115.         Pascal. The C version can be assembled with TASM (specify 
  116.         /JMASM51 on the command line) or MASM 5.1.
  117.  
  118.         To assemble:
  119.             tasm /DPASCAL spawn,spawnp;     For Turbo Pascal, near calls
  120.             tasm /DPASCAL /DFARCALL spawn,spawnp;  
  121.                                             For Turbo Pascal, far calls
  122.             ?asm spawn;                     For C (default small model)
  123.             ?asm /DMODL=xxx spawn;          For C (model 'xxx')
  124.          Example:
  125.             masm /DMODL=large spawn;            Large model C
  126.             tasm /DMODL=medium /JMASM51 spawn;  Medium model C
  127.  
  128.     SPAWNP.OBJ      SPAWN assembled for use with Pascal, near calls
  129.     SPAWNCS.OBJ     SPAWN assembled for use with C (small model)
  130.     SPAWNCL.OBJ     SPAWN assembled for use with C (large model)
  131.         
  132.         The C files have been assembled with the /MX switch
  133.         for case-sensitive external linking.
  134.  
  135.         Note for Turbo Pascal: You can use the near call version of
  136.         SPAWN even when compiling with "force far calls" by enclosing
  137.         the external definitions of do_spawn and prep_swap in file
  138.         exec.pas with {$F-} and {$F+}.
  139.         To avoid confusion when generating multiple language
  140.         versions, the Pascal OBJ-File was named "spawnp.obj".
  141.  
  142.     CHECKPAT.ASM   Utility function to check and resolve a path 
  143.  
  144.         This file is common to the C and Pascal versions.
  145.         It must be assembled with Turbo-Assembler for use with
  146.         Pascal. The C version can be assembled with TASM (specify 
  147.         /JMASM51 on the command line) or MASM 5.1.
  148.  
  149.         To assemble:
  150.             tasm /DPASCAL checkpat,checkpap;  For Turbo Pascal, near calls
  151.             tasm /DPASCAL /DFARCALL checkpat,checkpap;  
  152.                                               For Turbo Pascal, far calls
  153.             ?asm checkpat;                    For C (default small model)
  154.             ?asm /DMODL=xxx checkpat;         For C (model 'xxx')
  155.          Example:
  156.             masm /DMODL=large checkpat;            Large model C
  157.             tasm /DMODL=medium /JMASM51 checkpat;  Medium model C
  158.  
  159.     CHECKPAP.OBJ    CHECKPAT assembled for use with Pascal, far calls
  160.     CHECKPCS.OBJ    CHECKPAT assembled for use with C (small model)
  161.     CHECKPCL.OBJ    CHECKPAT assembled for use with C (large model)
  162.     CHECKPAT.PAS    Wrapper unit for checkpat (Pascal only)   
  163.  
  164.         The C files have been assembled with the /MX switch
  165.         for case-sensitive external linking.
  166.         The Pascal version must be assembled with the FARCALL switch
  167.         when used with the CHECKPAT.PAS unit. At least Turbo Pascal
  168.         version 5.5 seems to automatically generate a far call if an
  169.         external routine is defined in the interface part of the unit.
  170.  
  171.     EXEC.PAS        Interface routines and documentation for Turbo Pascal
  172.     EXEC.C          Interface routines for C
  173.     EXEC.H          Interface definitions and documentation for C
  174.     COMPAT.H        MS-C/TC Compatibility definitions for C
  175.  
  176.         These files prepare the parameters for the main spawn
  177.         function, and handle the file search and environment 
  178.         processing.
  179.  
  180.     EXTEST.C        C Test program for EXEC
  181.     EXTEST.PAS      Turbo Pascal Test program for EXEC
  182.  
  183.         The EXTEST program tests the functionality of the do_exec
  184.         function. It expects you to input a DOS-command and its
  185.         parameters, separated by a comma. Entering an empty line
  186.         will spawn a copy of COMMAND.COM without parameters.
  187.  
  188.    MAKEPAS          Make-file for Turbo Pascal (Borland Make) 
  189.    MAKETC           Make-file for Borland C++ (Borland Make) 
  190.    MAKEMS           Make-file for Microsoft C (MS NMAKE) 
  191.  
  192.  
  193. The Turbo Pascal version of EXEC.PAS includes replacement functions
  194. for the environment access functions 'envcount', 'envstr', and
  195. 'getenv', plus an additional function, 'putenv'. This function allows
  196. you to add strings to the environment for the spawned process. The
  197. definition is
  198.  
  199.         procedure putenv (envvar: string);
  200.  
  201. with 'envstr' containing a string of the form 'ENVVAR=value'. The '='
  202. is required. To delete an environment string, use 'ENVVAR='. Please
  203. use the environment functions from the EXEC unit only, do not mix them
  204. with calls to the DOS unit functions.
  205.  
  206.  
  207.                         SUPPORT
  208.                         =======
  209.  
  210. This software is in the Public Domain. This means that there is no
  211. restriction whatsoever on private or commercial use. No registration
  212. fees have to be paid, and no licenses are necessary for use. It also
  213. means that the author can not be held liable for any damages caused
  214. by the use of this software. You have the source, please check it out
  215. before use.
  216.  
  217. I will try my best to eliminate any bugs reported to me, and to 
  218. incorporate suggested enhancements and changes. However, my spare 
  219. time is limited, so I can not guarantee continued or individual 
  220. support. (But since I'm one of the owners of a consulting firm, you
  221. can always hire me to do it...). Please address all reports or
  222. questions to my business address: 
  223.  
  224.         Ferrari electronic GmbH
  225.         attn: Thomas Wagner
  226.         Beusselstrasse 27
  227.         D-1000 Berlin 21, Germany
  228.  
  229.         Phone: (+49 30) 396 50 21
  230.         Fax:   (+49 30) 396 80 20
  231.  
  232.         BIX:   twagner
  233.         UUCP:  oeschi@netmbx.UUCP (attn: Thomas Wagner)
  234.  
  235. But, please, if at all possible, do it in writing. Please do not 
  236. phone unless it is absolutely vital (or you have a business 
  237. proposal). I like to hear about any applications for EXEC, and 
  238. if you are visiting Berlin, I also invite you to drop by for a 
  239. talk. But I am usually not that happy when I am interrupted in my 
  240. paid work by a phone call requesting support for a free product. 
  241.  
  242. I will try to answer all letters and Faxes I receive. However, I 
  243. am usually not the fastest in this respect, so please be patient. 
  244. If you don't hear for me for a while, send me a short reminder. 
  245. The same goes for UUCP E-mail, since I'm not directly connected. 
  246. The preferred, and the fastest, method to reach me is through 
  247. BIX. Send mail to 'twagner'.
  248.  
  249. BIX (tm) is the BYTE Information Exchange, an electronic confe-
  250. rencing system created by McGraw-Hill, the publishers of the well 
  251. renowned BYTE magazine. BIX can be (and is) accessed from all 
  252. parts of the world. Although accessing BIX from outside the US 
  253. isn't exactly cheap (don't ask me what I have to pay each month), 
  254. the wealth of information available there, and the fast and 
  255. extensive help the other members can give you on all kinds of 
  256. hard- and software problems, makes it worth every Mark, Peseta, 
  257. Franc, or Ruble you have to spend. New versions and updates of 
  258. EXEC will first appear on BIX. 
  259.  
  260. To get more info on joining BIX, call the BIX Customer Service at 
  261. 800-227-2983 (U.S. and Canada), or 603-924-7681 (New Hampshire 
  262. and outside the U.S.) from 8:30 to 23:00 Eastern Time (-5 GMT). 
  263. BIX access currently is $39 for three months (flat fee, no extra 
  264. charges for connect time), plus the applicable telecomm charges 
  265. (Tymnet in the U.S. and Canada, your local PTT's Packet Net 
  266. charges from outside the U.S.). If you're calling from the US, 
  267. you can subscribe by dialling BIX direct at 617-861-9767. Hit the 
  268. return key, and enter "bix" at the 'login (enter "bix")' prompt. 
  269. At the 'Name?' prompt, enter "bix.flatfee". International users 
  270. living near a BT Tymnet node can access BIX through international 
  271. Tymnet at special low rates. Call the BIX helpline for Tymnet 
  272. access points and charges. Other international users will need an 
  273. account (NUI) with their local packet net. Please enquire at your 
  274. post/telecomm office for details. If you already own a NUI, enter 
  275. the BIX international network address (NUA), "310690157800", and 
  276. enter "bix.flatfee" at the 'Name?' prompt. 
  277.  
  278.  
  279.                         RESTRICTIONS
  280.                         ============
  281.  
  282. The "no return" mode of EXEC is included for completeness only. It
  283. has some disadvantages over the standard compiler functions for
  284. executing without return. In particular, files are not closed, and
  285. interrupt vectors used by the Run-Time-Library are not restored to
  286. the DOS defaults. If possible, use the standard RTL functions for
  287. this mode.
  288.  
  289. The assembler module "spawn" must not be the first module linked.
  290. Either put it into a library, or specify spawn.obj as one of the last
  291. objects in the link command or the Turbo project file. The spawn
  292. module will overwrite about 1k at the start of the program image.
  293. Although the contents of this area will be saved, they may not
  294. contain parts of the spawn module itself, since this could destroy
  295. the code being executed. The do_exec function will check for this
  296. condition, and return an error code if the program code could be in
  297. danger.
  298.  
  299. The calling program may not have interrupt handlers installed when
  300. calling the do_exec function. This includes handlers for Control C
  301. and critical errors. If you want to handle interrupts while the
  302. program is swapped, you will have to modify the spawn module such
  303. that the interrupt handlers are included in the resident part.
  304.  
  305. All open files will stay open during the EXEC call. This reduces the
  306. number of handles available to the child process. The "C_FILE_INFO"
  307. environment variable created by some C compilers on the standard C
  308. spawn call is not supported. If the NO_INHERIT flag is set in
  309. spawn.asm (default), all open files except for the first five
  310. standard handles will be "hidden" from the child, and thus will not
  311. be inherited. This increases the possible number of open files for
  312. the child, although the system-wide open file limit (the config.sys
  313. FILES= value) still must be high enough to support all open files.
  314.  
  315. Internal commands are not automatically processed. You can execute 
  316. those by loading the command interpreter (by passing an empty string 
  317. as the command name). For example:
  318.  
  319. (C)     retcode = do_exec ("dir", "*.*", USE_ALL, 0xffff, environ);
  320.         if (retcode == RC_NOFILE)
  321.            retcode = do_exec ("", "/c dir *.*", USE_ALL, 0xffff, environ);
  322.  
  323. (P)     retcode := do_exec ('dir', '*.*', USE_ALL, $ffff, true);
  324.         if (retcode = RC_NOFILE)
  325.            retcode := do_exec ('', '/c dir *.*', USE_ALL, $ffff, true);
  326.  
  327.  
  328.  
  329.                         CAUTIONS
  330.                         ========
  331.  
  332. The functions should be compatible with DOS versions down to DOS
  333. 2.21, but they have been tested under DOS 3.3, DOS 4.0, DOS 5.0, and
  334. DR-DOS 5.0 only.
  335.  
  336. Compiler compatibility has been tested for Borland C++ 2.0, Microsoft
  337. C 6.0a, and Turbo Pascal 5.5 only. I do not have access to other
  338. compilers.
  339.  
  340. Spawning a command that exits and stays resident (TSR), like PRINT or
  341. Sidekick, will fragment memory and prevent a return to the calling
  342. program. This should, however, not crash the system. Allocated EMS
  343. or XMS pages are released, a swap file is deleted.
  344.  
  345. If the program memory image is not contiguous, the swapping code has
  346. to use undocumented DOS-internals. In particular, the swapper has to
  347. modify DOS memory control blocks directly. In theory, this could lead
  348. to incompatibilities with later versions of DOS, or with DOS
  349. substitutes or emulators. In practice, no problems have been reported
  350. with any DOS version, including DOS 5.0 and the DR-DOS versions.
  351.  
  352. If the NO_INHERIT flag is set in spawn.asm, some undocumented fields
  353. in the PSP are used and modified. This should work with all DOS
  354. versions and clones, but you can set NO_INHERIT to 0 if you are
  355. afraid of potential problems.
  356.  
  357.  
  358.                         Revision History
  359.                         ================
  360.  
  361. Changes for version 3.0a to 3.1:
  362.  
  363. The capability to process BAT files and to handle redirection was
  364. added.  The program search order now exactly matches the DOS order
  365. with the exception of internal commands (there is no safe way to
  366. determine whether a command is internal or external). Redirection is
  367. optional.  The interface to do_exec did not change (redirection is
  368. handled by parsing the parameter string), but do_spawn takes three
  369. new parameters if redirection is enabled.
  370.  
  371. A routine was added (checkpat.asm) that checks and resolves a path
  372. name in addition to splitting it. This routine does some thorough
  373. checks on the supplied path and filename, and will handle critical
  374. errors (invalid drive, drive not ready) without user intervention.
  375. This routine is used to process the program file name, the command
  376. processor filename, and the temporary path. This routine is not
  377. dependent on the other EXEC/SPAWN routines, and thus might be
  378. useful for other applications.
  379.  
  380. Several new error codes allow better analysis of error conditions.
  381.  
  382. The temporary file path will now always be a complete path, so that a
  383. change of the default drive and directory while spawned can no longer
  384. cause the swap file to get lost.
  385.  
  386. Any parameters on the COMSPEC= environment string will be inserted
  387. into the command parameters when calling the command processor. This
  388. allows specification of environment size and other parameters when
  389. spawning.
  390.  
  391. The check for file existance was moved to checkpat.asm, and changed
  392. from a 'find first' operation to 'get file attributes'. This seems to
  393. be marginally faster, and avoids compiler dependencies.
  394.  
  395. The GETLANG program was corrected to use stderr to output the usage
  396. information.
  397.  
  398.  
  399. Changes for version 3.0 to 3.0a:
  400.  
  401. A minor bug in EXEC.C was fixed: a '<' was missing in a German
  402. comment, so that GETLANG E would gobble up a large part of the file.
  403.  
  404. A problem (feature? bug?) with the Turbo C/Borland C "stat" function
  405. always returning directories with a "read-only" attribute prevented
  406. the "TEMP" directory from being used. The Write permission for the
  407. directory is no longer checked.
  408.  
  409. The preallocation of the swap file introduced in Version 3.0 to make
  410. sure that the disk can hold the swap file causes a severe slowdown
  411. when the swap drive is a Novell Network drive. Two new "method" flags
  412. were introduced to circumvent this problem:
  413.  
  414.       NO_PREALLOC - never preallocate
  415.       CHECK_NET   - check for network drive, don't preallocate if net
  416.  
  417. If the file is not preallocated, the disk is not checked for
  418. sufficient space at all. Using the "get disk free space" call usually
  419. takes even longer than preallocation. This is not a big problem
  420. though, swapping simply will fail with error code 0x502 when the disk
  421. is full on swapping out.
  422.  
  423. Thanks to Tim Frost ('<' bug) and Tron Hvaring (stat and Novell
  424. problems) for their reports.
  425.  
  426.  
  427. Changes for version 3.0:
  428.  
  429. This is a major rewrite of the code in spawn.asm. The interface for
  430. do_exec and do_spawn has changed, the exec and extest files have been
  431. modified accordingly.
  432.  
  433. The main enhancement is support for XMS.
  434.  
  435. The code in spawn.c was modularized a tad, and a lot of comments were
  436. added. This should help in better understanding the code. Old bugs
  437. (versions 2.4 and 2.5 were buggy in handling non-swapping spawns)
  438. were eliminated.
  439.  
  440. The allocation of swap space has been separated from the actual
  441. swapping. Although not used in the current do_exec routine, this
  442. could be used to issue an informative message about where the
  443. swapping will go to, and to try other paths for the temporary file if
  444. allocation fails. You might elect to add support for this in the
  445. do_exec routine, just be careful not to modify the memory layout
  446. between the calls to prep_swap and do_swap.
  447.  
  448. The MCB blocks are no longer modified in preparation of the swap.
  449. Instead of using an internal chain with undocumented fields in the
  450. MCB, the MCB chain is now parsed multiple times. Since the chain
  451. normally consists of just a few elements, this will not severely
  452. impact execution performance. MCBs are now swapped out and restored
  453. in their original form, including the "unused" fields that are not
  454. really unused in DOS 4.0 and later versions.
  455.  
  456. Saving fragmented memory will now use less EMS space, since the
  457. blocks are packed tight. Previous versions started a new page for
  458. every MCB.
  459.  
  460. Memory blocks located "below" the PSP (including the environment
  461. block, unless it is needed for an environment copy) will now be
  462. swapped, too. This may increase available memory if DOS memory is
  463. fragmented.
  464.  
  465.  
  466. Things not done in this release:
  467.  
  468. The MCB chain still is modified directly. Although some users have
  469. suggested trying to call DOS to allocate the blocks, this has proven
  470. impractical in some tests. If memory is fragmented, getting DOS to
  471. allocate a block at an exact location is rather tedious. I will keep
  472. the suggestion in mind, but the current method works reliably with
  473. all known (and unknown) versions of DOS and its clones.
  474.  
  475. Another good suggestion not implemented in this version is the save
  476. and restore of the interrupt vector table to remove TSRs installed
  477. while the program was swapped out. It would be rather complex to find
  478. and release all memory blocks belonging to the TSR, and without
  479. releasing the TSRs memory, the program can not be swapped back in
  480. anyway, so restoring the interrupt table wouldn't help.
  481.  
  482.